/*
 * Copyright 2010 WithOne Co. Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 *     
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package jp.co.withone.osgi.gadget.controller.preference;

import javax.swing.JPanel;

/**
 * 設定画面を取得するためのインタフェース。
 * OSGiサービスとして登録する。
 * サービスプロパティには以下を設定する。
 * <ul>
 * <li>{@link #NAME}</li>
 * <li>{@link #PARENT}</li>
 * <li>{@link #CHILDREN}</li>
 * </ul>
 * @author t.funakky
 */
public interface Preference {

    /**
     * 設定画面名をサービスプロパティに設定するためのキー。
     * 本プロパティ値は設定画面のツリーに表示される。
     * 本プロパティ値の型は{@link java.lang.String}とする。
     */
    String NAME = "name";

    /**
     * 親設定画面名をサービスプロパティに設定するためのキー。
     * 本プロパティ値は設定画面のツリーに{@link #NAME}として指定された
     * サービスプロパティ値のノードの親ノードとして表示される。
     * 本プロパティ値の型は{@link java.lang.String}とする。
     * 本設定画面がルートノードの場合、サービスプロパティは設定しない。
     */
    String PARENT = "parent";

    /**
     * 子設定画面名をサービスプロパティに設定するためのキー。
     * 本プロパティ値は設定画面のツリーに{@link #NAME}として指定された
     * サービスプロパティ値のノードの子ノードとして表示される。
     * 本プロパティ値の型は{@link java.lang.String}とする。
     * 本設定画面が最下位のリーフノードの場合、サービスプロパティは設定しない。
     */
    String CHILDREN = "children";

    /**
     * 設定画面を取得する。
     * 設定画面のツリーで{@link #NAME}としてサービスプロパティの値に設定したノードを設定した際に
     * 本メソッドがコールバックされ、戻り値が設定画面として表示される。
     * @return 設定画面
     */
    JPanel getPage();

    /**
     * 設定画面の変更を適用する。
     * 設定画面で適用ボタンが押下された際にコールバックされる。
     * 変更が不要な場合は空実装とする。
     */
    void confirmed();

    /**
     * 設定画面の変更を取り消すする。
     * 設定画面で取り消しボタンが押下された際にコールバックされる。
     * 変更の取り消しが不要な場合は空実装とする。
     */
    void canceld();
}
